feat(access): let a grant open a UI surface, not only reach data - #899

What

A permission grant could reach data. Now it can also open a screen.

ui_surface names a navigation item or page in the admin UI — ocotillo.lexicon, ocotillo.location, and so on — using the same resource identifier the UI already checks in canAccessResource, so a lexicon term and a nav item cannot drift apart.

// a data grant, unchanged
{ "capability": "read", "data_type": "water level", "scope_type": "thing", "scope_id": 7 }

// a screen grant
{ "capability": "read", "ui_surface": "ocotillo.lexicon", "scope_type": "global" }

Based on feat/scope-based-access-control, not staging — it needs the ADR5 access tables and the list-all-grants route.

The no-wildcard rule is kept, not relaxed

data_type becomes nullable, which looks like a loosening. It is not. The rule it carried — a grant names its subject, and there is no term meaning "all" — is replaced by a strictly equivalent one:

Exactly one of data_type / ui_surface is set. Never neither, never both.

• Neither is the old MissingDataType, unchanged in spirit: a blanket grant is what published data nobody agreed to publish.
• Both is a new AmbiguousGrantSubject. A row naming both would be two grants wearing one revocation, and revoking the data half would silently take the screen away too. Write two grants so each can be revoked on its own.

The XOR is enforced in domain/access.py before any row is written, not as a check constraint, for the reason the scope rule is: so it holds for every writer and reads as one sentence.

A surface grant is always global

New ScopedSurfaceGrant. Navigation is app-wide — the UI asks "may this caller see this screen", never "for this well" — so a thing- or group-scoped surface grant could not match any request the UI makes. It is refused at the door rather than stored as a row that silently never applies.

Matching never treats None as a match

A data grant and a screen request both carry None on the axis not being asked about. Matching on None == None would make a data grant answer a screen question, so _subject_matches requires the asked axis to be present and equal. A request naming neither subject is a no — default deny, because a question this layer cannot answer is not a yes.

Surface area

Plus services.visibility.may_see_surface, a thin reading of may — surface grants are always global and always read, so callers do not restate either.

Widen-only by construction. This answers whether a grant opens a screen. The UI falls back to its role policy when the answer is no, so a missing grant can never take away what a role already allows, and a grants outage cannot lock an admin out.

Migration

a396d7d9928d. Adds ui_surface (nullable, FK to lexicon_term), makes data_type nullable. Existing rows all carry a data_type and are untouched.

The downgrade deletes surface grants before restoring NOT NULL. That is the honest direction: they are grants the old schema has no way to express, and giving them an invented data_type would grant data access nobody asked for. Both directions were run against a live database, with a surface grant present, and the row was removed as documented.

ui_surface is a lexicon category seeded from core/lexicon.json, not an enum type, so adding a screen later is not a migration.

Verification

• tests/test_domain_access.py — 46 pass, 13 new: the XOR, the global-only rule, None-is-not-a-match in both directions, and that a surface grant expires and revokes like any other.
• tests/test_access.py — 36 pass, 11 new, through the routes: grant, filter, decide, revoke, and both 422s.
• Full suite: 1475 passed, 84 skipped, 6 xpassed. The 3 failures in tests/transfers/test_contact_with_multiple_wells.py are a missing local gcs_credentials.json pointing into another checkout — unrelated, and failing the same way before this branch.
• black clean. flake8 reports only E501, which the repo already produces on these files untouched (black targets 88, there is no flake8 config).

One defect this caught in itself, worth noting: the first cut passed a bare Enum into the 422 detail, which is not JSON serializable. Fixed, and the route test that found it is in the suite.

Consumer

DataIntegrationGroup/OcotilloUI#365 adds the access console. The UI side of surface grants goes on top of this.